Configuring CWSerenade for TLS

Configuring CWSerenade for TLS

TLS (Transport Layer Security) is a communication protocol to manage the security of message transmission between CWSerenade and an external system, allowing you to encrypt the data passed between the client browser and the server.

Use the following steps to configure CWSerenade to use TLS communication.

Important: You must perform these steps on each of your CWSerenade application servers.

• Create SerenadeTLS Folder

• Verify Java Version and Update PATH Variable

• Create a keystore and private Key

• Create a Certificate Signing Request File or Sign the Security Certificate Using an External Resource

• Export the Security Certificate To Make It Available to Install on Clients

• Import the Security Certificate into the Java Repository

• Configure Tomee to Allow TLS Communications

• Logging in to the TLS Enabled CWSerenade Application

Expired certificates: See Expired Security Certificate for instructions on removing a security certificate once it has expired.

Create SerenadeTLS Folder

Under the root drive where CWSerenade is installed, create a folder and name it SerenadeTLS.

Verify Java Version and Update PATH Variable

Verify that your current Java version is the same version used to run CWSerenade and add it to the PATH variable.

1.	Advance to the following directory, where C: is the root directory where CWSerenade is installed: C:\Serenade\server\java
2.	The name of the folder located in the Java directory defines the version of Java you are using for CWSerenade. Example: jre7 If more than one folder exists, take note of the name of the folder with the highest name. For example, If the directory contains jre7 and jre8, take note of jre8.
3.	Add the following to the beginning of the PATH variable, where jre7 is the version of Java you noted in the previous step. C:\Serenade\server\java\jre7\bin To modify the PATH variable, advance to Start > Control Panel > System and Security > System and select Advanced System Settings. On the System Properties window, click Environment Variables.
	On the Environment Variables window, located the PATH variable and select Edit to modify its value.
4.	Verify the class path for the Java security programs. To verify: • Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window. • At the command prompt window, type keytool and press Enter. The system displays a usage list: Note: If you received an error instead of a usage list, make sure you updated the PATH variable as described in the previous step.

Create a keystore and private Key

1.	Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window.
2.	At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server and 365 is the number of days the keystore is valid. keytool -genkey -alias servername.domain.com -keyalg RSA -keystore c:\SerenadeTLS\tomcatkeystore -validity 365 Press Enter.
3.	The system displays the following questions. Answer each question as indicated below. • Keystore password: Enter serenade. • What is your first and last name: Enter the fully qualified server name. • What is the name of your organizational unit: Enter the name of your company. • What is the name of your organization: Enter the name of your company. • What is the name of your city or locality: Enter your city. • What is the name of your state or province: Enter your state or province. • What is the two-letter country code for this unit: Enter the two character country code (for example: US for United States, CN for Canada). The system displays what you entered and asks if it is correct. Enter yes. Enter key password for servername.domain.com: Press Enter to accept the default.
4.	To verify the keystore was created, advance to the following directory, where C: is the root drive where CWSerenade is installed. C:\SerenadeTLS In the SerenadeTLS folder, you should see a file named tomcatkeystore. • To self-sign the security certificate, see Create a Certificate Signing Request File. • To use an external resource, such as Verisign, to sign the security certificate, see Sign the Security Certificate Using an External Resource.

Create a Certificate Signing Request File

Use these steps if you wish to self-sign the security certificate; otherwise, see Sign the Security Certificate Using an External Resource.

Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window.

At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server:

keytool -certreq -keyalg RSA -alias servername.domain.com -file c:\SerenadeTLS\certreq.csr -keystore c:\SerenadeTLS\tomcatkeystore

Press Enter. When the system prompts you for the keystore password, type serenade.

Sign the Security Certificate Using an External Resource

You can use an external resource, such as Verisign, to sign the security certificate. Follow the instructions provided by the resource to sign the certificate. To self-sign the security certificate, see Create a Certificate Signing Request File.

Make sure the signed certificate reply is named serenadecert.cer.

When you receive the signed certificate reply, put it in the following directory, where C: is the root drive where CWSerenade is installed:

C:\SerenadeTLS

To install the certificate:

Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window.

At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server:

keytool -import -alias servername.domain.com -keystore c:\SerenadeTLS\tomcatkeystore -trustcacerts -file c:\SerenadeTLS\serenadecert.cer

Press Enter.

When the system prompts you for the keystore password, type serenade.

Export the Security Certificate To Make It Available to Install on Clients

Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window.

At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server:

keytool -export -keystore c:\SerenadeTLS\tomcatkeystore -file c:\SerenadeTLS\serenadecert.cer -alias servername.domain.com

Press Enter. When the system prompts you for the keystore password, type serenade.

To verify that the certificate was exported, advance to the following directory, where C: is the root drive where CWSerenade is installed.

C:\SerenadeTLS

In the SerenadeTLS folder, you should see a file named serenadecert.cer.

Import the Security Certificate into the Java Repository

You need to import the security certificate into the Java repository in order to enable the system to access web services via TLS.

Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window.

At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server:

keytool -import -keystore C:\ Serenade\server\java\jre7\lib\security\cacerts -file C:\SerenadeTLS\serenadecert.cer -alias servername.domain.com

Press Enter.

When the system prompts you for the keystore password, type changeit and press Enter.

When the system asks whether to trust the certificate, type yes and press Enter.

The system displays a message indicating the certificate was added to the keystore.

Configure Tomee to Allow TLS Communications

1.	Stop the SERENADE service if it is active; see Restarting CWSerenade.
2.	Advance to the following directory, where C: is the root drive where CWSerenade is installed: C:\Serenade\server\conf\server.xml
3.	In the jboss-web.sar folder, locate the file server.xml.
4.	Make a backup copy of the server.xml file in case you need to restore it.
5.	Open the server.xml file in a text editor and locate the following section: <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="YOURKEYSTORE" clientAuth="false" keystorePass="YOURPASSWORD" sslEnabledProtocols = "TLSv1,TLSv1.1,TLSv1.2" />
6.	Make the following changes: • Uncomment the block beginning with Connector port="8443" • Update the following attributes: • keystoreFile="C:\serenade\tls\serenadekeystore • keystorePass="serenade"
7.	The updated section should look like the following: <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="C:\serenade\tls\serenadekeystore" clientAuth="false" keystorePass="serenade" sslEnabledProtocols = "TLSv1,TLSv1.1,TLSv1.2" />
8.	Save and close the server.xml file.
9.	Advance to the following directory, where C: is the root drive where CWSerenade is installed: C:\Serenade\server\conf\cwdirectcpproperties\cwdirectcp_server.properties
10.	Make a backup copy of the cwdirectcp_server.properties file in case you need to restore it.
11.	Verify that the GWT_RESOURCE_URI property is set to the following: https://localhost:8443/SerenadeSeam/srs Note: This property may not exist; if that is the case, you will need to add it. When TLS communication is turned off, this property setting looks like the following: https://localhost:8080/SerenadeSeam/srs
12.	Restart the SERENADE service.

Logging in to the TLS Enabled CWSerenade Application

Use the following URLs to log in to the TLS enabled CWSerenade application:

To access CWSerenade in a browser window with address bar:

https:\\servername.domain.com:8443\jenasys

where servername is the name of the CWSerenade application server

To access CWSerenade in a separate browser window:

https:\\servername.domain.com:8443\CWSerenade.html

where servername is the name of the CWSerenade application server

Security certificate error: You will receive a web site security certificate error when you try to log in to CWSerenade if the browser does not trust the certificate. This may occur if you used a self-signed certificate, as described under Create a Certificate Signing Request File.

Example security certificate error screen:

Use the following steps to tell the browser to trust the certificate.

1.	Click on Continue to this website (not recommended) to display the CWSerenade sign on screen. Notice that the URL displays in red and Certificate Error displays.
2.	Click on Certificate Error to display the following window:
3.	Click View certificates to advance to the Certificate window. At this window, click Install Certificate.
4.	The system starts the Certificate Import Wizard. At the Welcome window, select Next.
5.	At the Certificate Store window, select Place all certificates in the following store, click Browse, and select Trusted Root Certification Authorities.
6.	Select Next until you reach the Completion window. At this window, select Finish.
7.	If a Security Warning window displays, select Yes.
8.	When a success notification displays, select OK.
9.	Close and reopen the browser and enter the URL to log in to CWSerenade. You should no longer receive a security certificate error.